home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / bufcall.z / bufcall
Encoding:
Text File  |  2002-10-03  |  16.9 KB  |  196 lines
  1.  
  2.  
  3.  
  4. bbbbuuuuffffccccaaaallllllll((((DDDD3333))))                                                        bbbbuuuuffffccccaaaallllllll((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _bbbb_uuuu_ffff_cccc_aaaa_llll_llll - call a function when a buffer becomes available
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  15.      _tttt_oooo_iiii_dddd______tttt _bbbb_uuuu_ffff_cccc_aaaa_llll_llll_((((_uuuu_iiii_nnnn_tttt______tttt _s_i_z_e_,,,, _iiii_nnnn_tttt _p_r_i_,,,, _vvvv_oooo_iiii_dddd _((((_****_f_u_n_c_))))_((((_))))_,,,, _llll_oooo_nnnn_gggg _a_r_g_))))_;;;;
  16.  
  17.    AAAArrrrgggguuuummmmeeeennnnttttssss
  18.      _s_i_z_e
  19.         Number of bytes in the buffer to be allocated (from the failed
  20.         _aaaa_llll_llll_oooo_cccc_bbbb(D3) request).
  21.  
  22.      _p_r_iPriority of the _aaaa_llll_llll_oooo_cccc_bbbb allocation request.
  23.  
  24.      _f_u_n_c
  25.         Function or driver routine to be called when a buffer becomes
  26.         available.
  27.  
  28.      _a_r_gArgument to the function to be called when a buffer becomes available.
  29.  
  30. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.      When a buffer allocation request fails, the function _bbbb_uuuu_ffff_cccc_aaaa_llll_llll can be used
  32.      to schedule the routine, _f_u_n_c, to be called with the argument, _a_r_g, when
  33.      a buffer of at least _s_i_z_e bytes becomes available.  _bbbb_uuuu_ffff_cccc_aaaa_llll_llll serves, in
  34.      effect, as a timeout call of indeterminate length.
  35.  
  36.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  37.      On success, _bbbb_uuuu_ffff_cccc_aaaa_llll_llll returns a non-zero value that identifies the
  38.      scheduling request.  On failure, _bbbb_uuuu_ffff_cccc_aaaa_llll_llll returns 0.
  39.  
  40. UUUUSSSSAAAAGGGGEEEE
  41.      When _f_u_n_c runs, all interrupts from STREAMS devices will be blocked.  On
  42.      multiprocessor systems, when _f_u_n_c runs all interrupts from STREAMS
  43.      devices will be blocked on the processor on which _f_u_n_c is running.  _f_u_n_c
  44.      will have no user context and may not call any function that sleeps.
  45.  
  46.      Even when _f_u_n_c is called, _aaaa_llll_llll_oooo_cccc_bbbb can still fail if another module or
  47.      driver had allocated the memory before _f_u_n_c was able to call _aaaa_llll_llll_oooo_cccc_bbbb.
  48.  
  49.      The _p_r_i argument is no longer used but is retained for compatibility.
  50.  
  51.      The non-zero identifier returned by _bbbb_uuuu_ffff_cccc_aaaa_llll_llll may be passed to
  52.      _uuuu_nnnn_bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3) to cancel the request.
  53.  
  54.    LLLLeeeevvvveeeellll
  55.      Base or Interrupt.
  56.  
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. bbbbuuuuffffccccaaaallllllll((((DDDD3333))))                                                        bbbbuuuuffffccccaaaallllllll((((DDDD3333))))
  70.  
  71.  
  72.  
  73.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  74.      Does not sleep.
  75.  
  76.      Driver-defined basic locks, read/write locks, and sleep locks may be held
  77.      across calls to this function.
  78.  
  79.     EEEExxxxaaaammmmpppplllleeee
  80.      The purpose of this service routine [see _ssss_rrrr_vvvv(D2)] is to add a header to
  81.      all _MMMM______DDDD_AAAA_TTTT_AAAA messages.  We assume only _MMMM______DDDD_AAAA_TTTT_AAAA messages are added to its
  82.      queue.  Service routines must process all messages on their queues before
  83.      returning, or arrange to be rescheduled.
  84.  
  85.      While there are messages to be processed (line 19), we check to see if we
  86.      can send the message on in the stream.  If not, we put the message back
  87.      on the queue (line 21) and return.  The STREAMS flow control mechanism
  88.      will re-enable us later when messages can be sent.  If _cccc_aaaa_nnnn_pppp_uuuu_tttt(D3)
  89.      succeeded, we try to allocate a buffer large enough to hold the header
  90.      (line 24).  If no buffer is available, the service routine must be
  91.      rescheduled later, when a buffer is available.  We put the original
  92.      message back on the queue (line 26) and use _bbbb_uuuu_ffff_cccc_aaaa_llll_llll to attempt the
  93.      rescheduling (lines 27 and 28).  If _bbbb_uuuu_ffff_cccc_aaaa_llll_llll succeeds, we set the _mmmm______tttt_yyyy_pppp_eeee
  94.      field in the module's private data structure to _BBBB_UUUU_FFFF_CCCC_AAAA_LLLL_LLLL.  If _bbbb_uuuu_ffff_cccc_aaaa_llll_llll
  95.      failed, we use _iiii_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt(D3) to reschedule us instead (line 30).  _mmmm_oooo_dddd_cccc_aaaa_llll_llll
  96.      will be called in about a half second [_dddd_rrrr_vvvv______uuuu_ssss_eeee_cccc_tttt_oooo_hhhh_zzzz_((((_5555_0000_0000_0000_0000_0000_))))].  When the
  97.      rescheduling has been done, we return.
  98.  
  99.      When _mmmm_oooo_dddd_cccc_aaaa_llll_llll runs, it will set the _mmmm______tttt_yyyy_pppp_eeee field to zero, indicating that
  100.      there is no outstanding request.  Then the queue's service routine is
  101.      scheduled to run by calling _qqqq_eeee_nnnn_aaaa_bbbb_llll_eeee(D3).
  102.  
  103.      If the buffer allocation is successful, we initialize the header (lines
  104.      37-39), make the message type _MMMM______PPPP_RRRR_OOOO_TTTT_OOOO (line 41), link the _MMMM______DDDD_AAAA_TTTT_AAAA message
  105.      to it (line 42), and pass it on (line 43).
  106.  
  107.      See _uuuu_nnnn_bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3) for the other half of this example.
  108.  
  109.       _1111  _ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr _{{{{
  110.       _2222    _uuuu_iiii_nnnn_tttt______tttt    _hhhh______ssss_iiii_zzzz_eeee_;;;;
  111.       _3333    _iiii_nnnn_tttt    _hhhh______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn_;;;;
  112.       _4444  _}}}}_;;;;
  113.       _5555  _ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_oooo_dddd _{{{{
  114.       _6666    _llll_oooo_nnnn_gggg    _mmmm______iiii_dddd_;;;;
  115.       _7777    _cccc_hhhh_aaaa_rrrr    _mmmm______tttt_yyyy_pppp_eeee_;;;;
  116.          _...._...._....
  117.       _8888  _}}}}_;;;;
  118.       _9999  _####_dddd_eeee_ffff_iiii_nnnn_eeee _TTTT_IIII_MMMM_EEEE_OOOO_UUUU_TTTT    _1111
  119.      _1111_0000  _####_dddd_eeee_ffff_iiii_nnnn_eeee _BBBB_UUUU_FFFF_CCCC_AAAA_LLLL_LLLL    _2222
  120.          _...._...._....
  121.      _1111_1111  _mmmm_oooo_dddd_ssss_rrrr_vvvv_((((_qqqq_))))    _////_**** _aaaa_ssss_ssss_uuuu_mmmm_eeee _oooo_nnnn_llll_yyyy _MMMM______DDDD_AAAA_TTTT_AAAA _mmmm_eeee_ssss_ssss_aaaa_gggg_eeee_ssss _eeee_nnnn_qqqq_uuuu_eeee_uuuu_eeee_dddd _hhhh_eeee_rrrr_eeee _****_////
  122.      _1111_2222        _qqqq_uuuu_eeee_uuuu_eeee______tttt _****_qqqq_;;;;
  123.      _1111_3333  _{{{{
  124.      _1111_4444    _mmmm_bbbb_llll_kkkk______tttt _****_bbbb_pppp_;;;;
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. bbbbuuuuffffccccaaaallllllll((((DDDD3333))))                                                        bbbbuuuuffffccccaaaallllllll((((DDDD3333))))
  136.  
  137.  
  138.  
  139.      _1111_5555    _mmmm_bbbb_llll_kkkk______tttt _****_mmmm_pppp_;;;;
  140.      _1111_6666    _ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr _****_hhhh_pppp_;;;;
  141.      _1111_7777    _ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_oooo_dddd _****_mmmm_oooo_dddd_pppp_;;;;
  142.      _1111_8888    _mmmm_oooo_dddd_pppp _==== _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_oooo_dddd _****_))))_qqqq_----_>>>>_qqqq______pppp_tttt_rrrr_;;;;
  143.      _1111_9999    _wwww_hhhh_iiii_llll_eeee _((((_((((_mmmm_pppp _==== _gggg_eeee_tttt_qqqq_((((_qqqq_))))_)))) _!!!!_==== _NNNN_UUUU_LLLL_LLLL_)))) _{{{{
  144.      _2222_0000        _iiii_ffff _((((_!!!!_cccc_aaaa_nnnn_pppp_uuuu_tttt_((((_qqqq_----_>>>>_qqqq______nnnn_eeee_xxxx_tttt_))))_)))) _{{{{
  145.      _2222_1111            _pppp_uuuu_tttt_bbbb_qqqq_((((_qqqq_,,,, _mmmm_pppp_))))_;;;;
  146.      _2222_2222            _rrrr_eeee_tttt_uuuu_rrrr_nnnn_;;;;
  147.      _2222_3333        _}}}}
  148.      _2222_4444        _bbbb_pppp _==== _aaaa_llll_llll_oooo_cccc_bbbb_((((_ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr_))))_,,,, _BBBB_PPPP_RRRR_IIII______MMMM_EEEE_DDDD_))))_;;;;
  149.      _2222_5555        _iiii_ffff _((((_bbbb_pppp _====_==== _NNNN_UUUU_LLLL_LLLL_)))) _{{{{
  150.      _2222_6666            _pppp_uuuu_tttt_bbbb_qqqq_((((_qqqq_,,,, _mmmm_pppp_))))_;;;;
  151.      _2222_7777            _mmmm_oooo_dddd_pppp_----_>>>>_mmmm______iiii_dddd _==== _bbbb_uuuu_ffff_cccc_aaaa_llll_llll_((((_ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr_))))_,,,, _BBBB_PPPP_RRRR_IIII______MMMM_EEEE_DDDD_,,,,
  152.      _2222_8888                                 _mmmm_oooo_dddd_cccc_aaaa_llll_llll_,,,, _((((_llll_oooo_nnnn_gggg_))))_qqqq_))))_;;;;
  153.      _2222_9999            _iiii_ffff _((((_mmmm_oooo_dddd_pppp_----_>>>>_mmmm______iiii_dddd _====_==== _0000_)))) _{{{{
  154.      _3333_0000               _mmmm_oooo_dddd_pppp_----_>>>>_mmmm______iiii_dddd _==== _iiii_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt_((((_mmmm_oooo_dddd_cccc_aaaa_llll_llll_,,,, _((((_llll_oooo_nnnn_gggg_))))_qqqq_,,,,
  155.      _3333_1111                                     _dddd_rrrr_vvvv______uuuu_ssss_eeee_cccc_tttt_oooo_hhhh_zzzz_((((_5555_0000_0000_0000_0000_0000_))))_,,,, _pppp_llll_ssss_tttt_rrrr_))))_;;;;
  156.      _3333_2222               _mmmm_oooo_dddd_pppp_----_>>>>_mmmm______tttt_yyyy_pppp_eeee _==== _TTTT_IIII_MMMM_EEEE_OOOO_UUUU_TTTT_;;;;
  157.      _3333_3333            _}}}} _eeee_llll_ssss_eeee _{{{{
  158.      _3333_4444               _mmmm_oooo_dddd_pppp_----_>>>>_mmmm______tttt_yyyy_pppp_eeee _==== _BBBB_UUUU_FFFF_CCCC_AAAA_LLLL_LLLL_;;;;
  159.      _3333_5555            _}}}}
  160.      _3333_6666            _rrrr_eeee_tttt_uuuu_rrrr_nnnn_;;;;
  161.      _3333_7777        _}}}}
  162.      _3333_8888        _hhhh_pppp _==== _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr _****_))))_bbbb_pppp_----_>>>>_bbbb______wwww_pppp_tttt_rrrr_;;;;
  163.      _3333_9999        _hhhh_pppp_----_>>>>_hhhh______ssss_iiii_zzzz_eeee _==== _mmmm_ssss_gggg_dddd_ssss_iiii_zzzz_eeee_((((_mmmm_pppp_))))_;;;;
  164.      _4444_0000        _hhhh_pppp_----_>>>>_hhhh______vvvv_eeee_rrrr_ssss_iiii_oooo_nnnn _==== _1111_;;;;
  165.      _4444_1111        _bbbb_pppp_----_>>>>_bbbb______wwww_pppp_tttt_rrrr _++++_==== _ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _hhhh_dddd_rrrr_))))_;;;;
  166.      _4444_2222        _bbbb_pppp_----_>>>>_bbbb______dddd_aaaa_tttt_aaaa_pppp_----_>>>>_dddd_bbbb______tttt_yyyy_pppp_eeee _==== _MMMM______PPPP_RRRR_OOOO_TTTT_OOOO_;;;;
  167.      _4444_3333        _bbbb_pppp_----_>>>>_bbbb______cccc_oooo_nnnn_tttt _==== _mmmm_pppp_;;;;
  168.      _4444_4444        _pppp_uuuu_tttt_nnnn_eeee_xxxx_tttt_((((_qqqq_,,,, _bbbb_pppp_))))_;;;;
  169.      _4444_5555    _}}}}
  170.      _4444_6666  _}}}}
  171.      _4444_7777  _mmmm_oooo_dddd_cccc_aaaa_llll_llll_((((_qqqq_))))
  172.      _4444_8888   _qqqq_uuuu_eeee_uuuu_eeee______tttt _****_qqqq_;;;;
  173.      _4444_9999  _{{{{
  174.      _5555_0000   _ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_oooo_dddd _****_mmmm_oooo_dddd_pppp_;;;;
  175.      _5555_1111   _mmmm_oooo_dddd_pppp _==== _((((_ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_oooo_dddd _****_))))_qqqq_----_>>>>_qqqq______pppp_tttt_rrrr_;;;;
  176.      _5555_2222   _mmmm_oooo_dddd_pppp_----_>>>>_mmmm______tttt_yyyy_pppp_eeee _==== _0000_;;;;
  177.      _5555_3333   _qqqq_eeee_nnnn_aaaa_bbbb_llll_eeee_((((_qqqq_))))_;;;;
  178.      _5555_4444  _}}}}
  179.  
  180. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  181.      _aaaa_llll_llll_oooo_cccc_bbbb(D3), _eeee_ssss_bbbb_aaaa_llll_llll_oooo_cccc(D3), _eeee_ssss_bbbb_bbbb_cccc_aaaa_llll_llll(D3), _iiii_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt(D3), _uuuu_nnnn_bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3)
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  190.  
  191.  
  192.                                                                         PPPPaaaaggggeeee 3333
  193.  
  194.  
  195.  
  196.